Shareware Grab Bag

home *** CD-ROM | disk | FTP | other *** search

/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / tcdebug4.arc / TCDEBUG.DOC < prev next >

Wrap

Text File | 1987-10-03 | 27.0 KB | 991 lines

October 3, 1987 TCdebug Version 0.04 (C) Copyright 1987 by L. David Baldwin. All Rights Reserved. Further copyright information given below OVERVIEW TCdebug is an experimental source code debugger for use in debugging Turbo C (tm) Programs on the IBM-PC (tm). Its goal is to allow source code debugging in all of Turbo C's memory models and with most of the possible compile and link options. TCdebug allows you to: 1. View your source code (and, optionally, the assembly language code) while debugging. 2. Trace the operation of your program by source code lines or by assembly language instructions. 3. Insert breakpoints in your program by function name, by line number, or hexadecimal address. 4. Examine (and change) simple global variables by symbolic name. Local variables may also be examined and changed, but require that the proper displacement on the stack be known. 5. Set up a Watch window to keep continuous tabs on a variable. TCdebug is not a finished program. It is being released at this time to get an indication of interest and to obtain assistance in finding bugs and other problems. TCdebug is designed exclusively for debugging Turbo C programs. It should not be used on programs generated by other compilers. SYSTEM REQUIREMENTS 1. An IBM-PC, AT, or compatible. Screen compatibility is a must. 2. PC-DOS 2.0 or above. 3. Approximately 135k more memory than would normally be required to run the program to be tested. PREPARATION TCdebug requires that a Map file for your program be present to supply information on the program symbols and line number locations. When compiling and linking with TC, the options can be set with O/C/C/L and O/L/M/P. With TCC use -M and -y. 1 It is also highly desirable that the program to be tested be compiled with the 'standard stack frame' option on. Using TC, set this option with O/C/C/S. With TCC, use -k (The manual says -Y but that's apparently a typo). When starting a debugging session, the following files should be on the default drive: PROG.EXE (or, optionally, .COM for the Tiny Model) PROG.MAP the map file various.C all the source files for the program (or at least all that will be accessed.) OPERATION TCdebug may be started by entering the filename of the program to be debugged and any parameters which it requires on the command line, as: TCdebug PROG <other stuff> Here, PROG is the name of the program to be tested with EXE being the default extension. <other stuff> will be passed on to PROG as its command line when execution begins. If TCdebug is called without parameters, a request will be made for them. When execution begins, TCdebug loads the Map file, the EXE file and reports some facts about the program. Note should be made of whether pointers are regarded as Near or Far by default as this will be important when displaying pointers later. After "hitting any key", the program is executed to "main()" and the debugging screen appears. The debugging screen is divided into two parts. The lower section is the command and data section. The '*' is a prompt for one of the commands described later. The top part of the screen displays the program source code text which at this point will be centered at the first statement in main(). Source code line numbers appear at the left with the current line (the one to be executed next) being highlighted. Dividing the two portions of the debugging screen is a line which shows the name of the source file presently displayed. Two keys which can be tried at this point are the F9 and F10 keys. The F9 key toggles into and out of the assembly mode. When in assembly mode, the assembly language instructions of the program are displayed with the source code lines interspersed. The F10 key toggles between the debugger screen and the screen which receives program output. 2 SPECIAL KEYS FOR VIEWING TEXT The following keys may be used to change the text being displayed: Pg Up Pg Dn Move the display up or down one page. ^Pg Up ^Pg Dn Move to the start or end of the current file. Up arrow Down arrow Scroll up or down one line. ^Left Arrow (with Scroll Lock on) ^Right Arrow (with Scroll Lock on) Scroll horizontally left and right. F9 key Toggle in and out of assembly mode. F10 key Toggle between the debug screen and the screen of the program under test. Alt-U Move dividing line up one line. Alt-D Move dividing line down one line. Note that the toggling of the Scroll Lock key effects the action of some of the special keys. The text display may also be changed using the View command described later. COMMAND EDITOR Commands are entered at the '*' prompt. When entering commands, the following keys may used to edit the command: (They perform the same functions as they do in the Turbo C editor.) ^A,^S,^D,^F,^G,^T,^H,^V,^Y,LFARW,RTARW,^LFARW,^RTARW, Ins, Del, Backspace The Insert mode (default) is indicated by a slightly fatter cursor. The cursor is normal in the Overwrite mode. In addition, a stack of the last 6 commands (those having more than 3 characters) is maintained. The F3 key accesses the stored commands from the most recent to the oldest and the F5 key accesses them in the reverse order. These old commands may be used as is or may be modified by editing them. Note that commands are not acted upon until the Enter key is hit. (The cursor does not have to be at the line end to enter the command.) 3 COMMAND PARAMETERS TCdebug uses one or two letter commands. The command is often followed by one or more parameters. Parameters are delimited from the command and each other using spaces. The one exception to this is the format parameter which is preceded by a comma. The parameters which may be used are: <Symbol> A C source code symbol representing a function name or variable as appropriate. The leading underbar added by the compiler has been stripped off, so symbols are entered exactly as used in the source program. Case is significant (unless the non case sensitive link option was selected). The special symbols, _AX, _AL, _BX, etc. may be used to refer to the hardware registers. A special symbol, rtn (or RTN), refers to the return address of the current function. For this symbol to function reliably, the program should be compiled with the 'standard stack frame' option on. Currently, this symbol can only be accessed if the current CS:IP is on an exact source line number. Examples: V rtn Find out who called this function. G RTN Execute the remainder of this function, return to caller. <Line Number> Line numbers are entered as <filename>\<number> as: myprog.c\345 In most cases, the <filename> part can be dropped. An entry of the form \345 implies line number 345 in the currently displayed source file. (Currently, the '\' also may be dropped and a simple decimal entry will do. However, the '\' may be required in future versions.) <Hexaddress> Normal numerical entry in TCdebug is decimal with hex entries allowed by preceding them with '0x'. However, numerical address entries must be entered in hex to distinguish them from line numbers. A <hexaddress> takes the following form: 0x1234:0x1ABC es:bx+2 SS:BP-0X5a 4 As indicated above, register names are allowed in address specifications. The _current_ value in the register is used--the address does not change if the register value later changes. The segment part of the <hexaddress> may be dropped as in: bp-0xA 0x123 bx If no segment is present in the entry, there is an implied segment. The rules for determining the implied segment are: 1. If the BP register is used, SS is implied. 2. If BX,SI,DI are used (but not BP), DS is implied. 3. If none of the above and a data entry is expected, DS is implied. 4. If a code address is expected, the current CS is implied. <Format> Format parameters are entered as one or two letters preceded by a comma. Case is significant. The purpose of the <format> parameter is to inform TCdebug of the size and type of a variable as this information is not available in the Map file. <format> parameters correspond to those used in the C 'printf' function. Currently supported are: c,s,i,d,u,x,X,o,p,g,G,li,ld,lx,lX,lo,Np,Fp,lg,lG For the p (pointer) format, the default pointer size for the selected memory model is used. This size is indicated in the information presented at startup. To override the default, use either N or F as appropriate. The c (character) format has been used as a catchall for byte size items. Display is in quoted character form, decimal, and hex. Change entries may be made using any of those forms. COMMANDS G (Go) Format: G [<parameter> [<parameter..]] The Go command starts execution of the program under test. Execution will continue until a breakpoint is reached or the program terminates. One or more breakpoints may be entered with the Go command. These breakpoints are called temporary breakpoints as they are in effect only until the first stopping point is reached. Any temporary breakpoint would then have to reentered with the next Go command if desired. 5 Examples: G Start execution with no temporary breakpoints. (There might be some permanent breakpoints, however.) G \345 funct1 0x113 Start execution with temporary breakpoints at line number 345, at the start of function, funct1, and at address CS:0x113. In addition, there might be other permanent breakpoints in effect. T (Trace) Format: T (or F7 key) In source code mode, execute the code on the current line. Execution will stop at the next encountered line number. If the current line contains a function call, the break will be at the start of the function. In assembly mode (assembly code is displayed), execute the next assembly language instruction. N (Next) Format: N (or F8 key) In either the source code or assembly mode, Next will execute the program, stopping at the next line number. The difference between the Trace and the Next command is that, if the current line contains a function call, Next will completely execute the function whereas Trace will Trace through the function. P (Permanent breakpoint) Format: [-]P [<parameter>] [<pass count>] The P command is used to specify permanent breakpoints. Unlike temporary breakpoints, permanent breakpoints remain in effect until removed (using a '-' preceding the P command). If no parameter is entered, the breakpoints in effect are listed. An optional pass count may be included when adding a breakpoint. The pass count indicates how many times the breakpoint will be passed before the program is actually interrupted. 6 Examples: P List all permanent breakpoints. -P Delete all permanent breakpoints. P moda.c\345 Install a breakpoint at line 345 in file moda.c. -P funct1 Remove a breakpoint at function funct1. P 0x34b 10 Install a breakpoint at CS:034B. The break will occur at the 11th execution of the instruction. BE, BC (Conditional Breakpoints) Formats: BE <parameter>, <format> <value> (Break when Equal to value) BC <parameter>, <format> (Break when there is a Change) B (List conditional breakpoints) -B [<number>] (delete one or more conditionals) Conditional breakpoints allow TCdebug to interrupt program execution whenever it finds that a variable has changed or becomes equal to a specified value. TCdebug checks each one of the conditional breakpoints whenever it regains control of the program. Normally, when using conditional breakpoints, the GT (Go in Trace mode) command should be used to allow the variable checks to be made at each source line. String variables are compared over the first 10 characters. Examples: BC str,s Break when the string variable, str, changes. BE *np,i 39 Break when the integer pointed to by np equals 39. -B2 Delete conditional breakpoint #2. GT (Go in Trace mode) Format: GT [<parameter> [<parameter..]] The GT command is a special version of the G (Go) command for use with conditional breakpoints. Both commands have the same syntax. When the GT command is used, the execution of the program is interrupted briefly at each source line so that the specified conditions can be checked. Because of the extra overhead involved with the GT command, program execution is very much slower than with the G command. Example: GT \334 Start execution of the program stopping at the first occurrence of: line 334, reaching a permanent breakpoint, or one of the conditions specified by a conditional breakpoint. 7 V (View text) Format: V [<parameter>] The View command may be used to change the text being observed in the text window. If no parameter is entered, the text will be centered around the current line. Examples: V initscreens View text at function initscreens. V \545 View text around line 545. VF (View File) Format: VF <filename> The View command is for viewing the program source files. The VF command allows any ASCII file to be displayed. E (Examine/change variable) Format: E <symbol>|<hexaddress> , <format> The Examine/change command allows the the value of a simple variable to be displayed and optionally changed. Global variables may be referred to symbolically. Auto and static variables must be referred to by a <hexaddress>. Pointers may be resolved using one or more '*'s preceding the symbol or address. <format> indicates the type of display wanted. After a variable value is displayed in response to the Examine/change command, a new value may be optionally entered followed by the Enter key. The Enter key by itself is used if no new value is desired. String variables are displayed as a string within quotes. When specifying a change to a string variable, the new string should be enclosed in double quotes. A null string is specified by two quotes enclosing nothing. 8 Examples: E flt,g E dble,lg E *st,c E es:bx,u E bp-0x52, s When referring to registers, note that there is a difference between the register symbols with underbars and those without the underbars, so that: E ds:bx,x Examine/change the hex integer at the address ds:bx. E bx,x The same thing (DS is implied). E _BX,x Examine/change the BX register. W Watch variable Format: W <symbol>|<hexaddress> , <format> [-]W [<number>] The Watch command opens up a watch window so that the specified variable is displayed continuously. The value displayed is updated whenever TCdebug regains control. The syntax for watch variable entry is identical to that used with the Examine command. When watch variables are displayed, they are given a number. The number is useful for selectively deleting them using the -W command. Examples: W var1, u Watch the unsigned variable, var1 W *bp-4,c Watch the char variable pointed to by SS:BP-4 W _AL,c Watch the AL register -W 1 Delete watch variable #1 -W Delete all watch variables D (Display Memory) Format: D <symbol>|<hexaddress> , <format> -D The Display command opens up a three line display window displaying memory contents at the address given by <parameter> in the format given by <format>. This display window may be scrolled using the following keys when Scroll Lock is toggled on: Up Arrow Down Arrow Move up or down one line (Scroll Lock on) 9 Pg Up Pg Dn Move up or down two lines (Scroll Lock on) Examples: D ptrs,Fp Display memory at ptrs in far pointer format. D dbles,lG Display memory at dbles in double format. D *es:bx,s Display memory as pointed to by es:bx in string or character format. -D Close the display window. X (Translate symbols to addresses or addresses to symbols) Format: X <symbol> X <address> The X command allows the address associated with a symbol to be determined or vice versa. R (Register Display) Format: R The Register display command displays the current machine register contents. RE (Restart program under test) Format: RE Reloads a fresh version of the test program and restarts it from the beginning. Breakpoints and watch variables remain in effect. WD (Window Divide) Format: WD [n] The Window Divide command allows the line dividing the screen to be moved up or down. n is the desired line position. If n is not entered, the line position is not changed but the screen is refreshed. The line dividing the screen may also be moved one line at a time using Alt-U (Up) or Alt-D (Down). 10 Q (Quit) Format: Q The Quit command ends debugging without running the program under test to completion. However, the program's exit() routine is executed, so that files are closed, etc. You will be asked if you wish to restart the program. DG (DebuG) Format: DG This command is used to enter an optional external assembly language debugger. It is used mainly for debugging TCdebug. HINTS It is possible to insert breakpoints in the source code using geninterrupt(3). These breakpoints cannot be removed by TCdebug but may be useful for conditional breaks. For instance: if (i==49) geninterrupt(3); If you mistakenly Trace into a function you wanted to skip using Next, use G rtn. Actually, it's best to do a V rtn first to make sure that the 'rtn' symbol is working correctly. If, in the assembly mode, you trace into a library routine and can't find your way out, toggle out of assembly mode (F9). Even if the source code screen is blank at this time, a single Trace will get you to the next line number. Avoid assembly tracing of the 8087 emulation code. Auto (stack) variables can be Examined or Watched by using the disassembly listing to determine their position on the stack relative to the BP register. When doing this, be sure that the BP register is valid. In particular, the BP register is not valid immediately on entry to the function. One source line trace must be made (or several assembly instructions passed) before the BP register is correct. The Huge memory model has the same sort of problem with the DS register which changes between modules. In this case, it only effects the disassembly listing. The data symbols will not be correctly listed until the DS register has been setup. 11 RESTRICTIONS, PROBLEMS, BUGS The following are current limits (somewhat arbitrarily set). Permanent and temporary breakpoints are limited to 5 each. Maximum file size for displayed files = 40k. Maximum number of line numbers (only those with code count) = 3000. Maximum number of program modules accommodated = 20. Maximum number of symbols = 700. Maximum number of watch variables = 4 Maximum number of conditional breakpoints = 3 A simple screen swap is currently used. This limits debugging to text only programs. Snow may be horrendous at this time. The map file for the Tiny memory model has some peculiarities in data addresses which I haven't got figured out yet. This affects a number of library data symbols but only seems to affect one or two source symbols. The problem shows up in the assembly listing where the affected symbols are not correctly displayed. The 8087 emulation code turns into a mess when disassembly is attempted. Currently, non default pointers cannot be resolved by the 'E' or 'W' commands. That is: E *st,c will always resolve st as a far pointer if the default is far. Probably some sort of cast will have to allowed, as: E *(near*)st,c COPYRIGHT Documentation and Program (C) Copyright 1987 by L. David Baldwin. All Rights Reserved. TCdebug may be copied and distributed freely by individuals to friends and acquaintances providing that no fee is charged and it is not part of a package for which a charge is made. The uploading of TCdebug to any bulletin board except that of the Borland Sig (CompuServe) is expressly forbidden. 12 TRADEMARKS IBM-PC is a trademark of International Business Machines Corporation. Turbo C is a trademark of Borland International Inc. Please report all bugs, suggestions, and problems to Dave Baldwin, CompuServe ID #76327,53. 13 APPENDIX A -- COMPILER OPTIONS As mentioned earlier, it is mandatory that the map file generation and line number options be turned on. The effect of some of the other compiler options on debugging are discussed below. Some of this is just guess work at this stage as not all have actually been tested. Standard Stack Frame This option is highly desirable as the BP register must be set up in order for the 'rtn' symbol to work. If this option is not used, any function which has many auto variables will still have a standard stack frame, so it is still possible to use 'rtn' in some cases. The safest method is to do a V rtn or X rtn first to see if the return address makes sense before committing yourself to a G rtn. Register Optimization Borland suggests off. I haven't tried this one but I suspect that it confuses things somewhat. Those adept at assembly language may not have too much trouble. Jump Optimization Same as register optimization. 80186/80286 Code Generation Off is best here. The disassembler in TCdebug currently does not understand the new instructions. Use Register Variables When this option is on, you may have to figure out which variables the compiler decided to store in registers. 8087 vs Emulation If you have a choice, by all means select straight 8087. The emulated code does not disassemble in any meaningful way. Non Case Sensitive Link If this option is selected, symbols will appear in uppercase. Symbol entries may be made in either case. 14 APPENDIX B -- SOURCE CODE FORMATTING With modern compilers, line numbers often do not correspond to the code generated in the manner that you might expect. Layout of the source code can help in this respect. While you probably don't want to reformat all your present code, you may want to change your formatting for code yet to be written. The most obvious format change is to only have one source statement per line. With more than one statement on a line, line numbers can't be used to set a breakpoint on the second statement and the Trace command will trace multiple statements. Statements split between two lines do not cause much trouble. The 'else' in an 'if' statement causes a difficulty. Consider the following code: 100 if (...) 101 {..do something..} 102 else {..do something else..} 103 To put a breakpoint on the ..do something else.. one might try a break on line 102. But the else here actually generates a jump instruction (to line 103) so ..do something else.. is inaccessible except by using a code hexaddress. A better format is: 100 if (...) 101 {..do something..} 102 else 103 {..do something else..} 104 The 'for' statement also causes problems. The decision code for the 'for' statement is actually done at the bottom of the loop and often is included as part of the next line where you would normally think the statement was completed. The best solution here is to add a blank line after the 'for' statement loop. In short, it's best to use plenty of vertical spacing and blank lines. Also take a peek at the assembly code to see what's going on. 15